This crate provides a winit-based backend platform for imgui-rs.
A backend platform handles window/input device events and manages their
state.
# Using the library
There are five things you need to do to use this library correctly:
1. Initialize a `WinitPlatform` instance
2. Attach it to a winit `Window`
3. Pass events to the platform (every frame)
4. Call frame preparation callback (every frame)
5. Call render preparation callback (every frame)
## Complete example for winit 0.20+ (without a renderer)
```rust,no_run,ignore
# // TODO: Remove ignore when only one winit version is used
use imgui::Context;
use imgui_winit_support::{HiDpiMode, WinitPlatform};
use std::time::Instant;
use winit::event::{Event, WindowEvent};
use winit::event_loop::{ControlFlow, EventLoop};
use winit::window::{Window};
let mut event_loop = EventLoop::new();
let mut window = Window::new(&event_loop).unwrap();
let mut imgui = Context::create();
// configure imgui-rs Context if necessary
let mut platform = WinitPlatform::init(&mut imgui); // step 1
platform.attach_window(imgui.io_mut(), &window, HiDpiMode::Default); // step 2
let mut last_frame = Instant::now();
let mut run = true;
event_loop.run(move |event, _, control_flow| {
match event {
Event::NewEvents(_) => {
// other application-specific logic
last_frame = imgui.io_mut().update_delta_time(last_frame);
},
Event::MainEventsCleared => {
// other application-specific logic
platform.prepare_frame(imgui.io_mut(), &window) // step 4
.expect("Failed to prepare frame");
window.request_redraw();
}
Event::RedrawRequested(_) => {
let ui = imgui.frame();
// application-specific rendering *under the UI*
// construct the UI
platform.prepare_render(&ui, &window); // step 5
// render the UI with a renderer
let draw_data = ui.render();
// renderer.render(..., draw_data).expect("UI rendering failed");
// application-specific rendering *over the UI*
},
Event::WindowEvent { event: WindowEvent::CloseRequested, .. } => {
*control_flow = ControlFlow::Exit;
}
// other application-specific event handling
event => {
platform.handle_event(imgui.io_mut(), &window, &event); // step 3
// other application-specific event handling
}
}
})
```
## `winit` versions and features.
This crate has several features which control the version of winit which is
used.
The following versions are supported, controlled by the listed feature.
- The `winit-25` feature uses winit versions compatible with `0.25`. This is
on by default, so to use any other version you need to disable this crates
default features.
- The `winit-24` feature supports winit versions `0.24`.
- The `winit-23` feature uses winit versions compatible with `0.23`.
- The `winit-22` feature uses winit versions compatible with `0.22`.
- The `winit-20` feature should support winit either `0.20` or winit `0.21`.
- The `winit-19` feature should support winits older than `0.19` (possibly
back to winit 0.16.*, but this isn't regularly tested and may not work).
If multiple `winit-*` features are enabled, and it is a debug build (as
determined by `debug_assertions`), we will log a warning to stderr during
init. This can be disabled by either turning on the `no-warn-on-multiple`
feature, fixing the configuration, or disabling `debug_assertions`.
Conversely, if no `winit-*` features are enabled, we will fail to compile.
This is not an issue generally, as by default we turn on `winit-25`.
All of this is in attempt to preserve the additive nature of features (while
still helping users notice project configuration issues), however it's done
fairly weakly as our this crate's API isn't 100% identical across winit
versions.
### Using an older `winit` version
To use an older version, you must configure `default-features = false` in
your `Cargo.toml`:
```toml
[dependencies.imgui-winit-support]
version = "0.6"
features = ["winit-$YOUR_VERSION_HERE"]
default-features = false
```
### Old `winit` compatibility
No guarantee is made on how long this crate will support legacy versions of
`winit`, but we'll try to follow these rules:
- Versions which are still in widespread use in the ecosystem will be
supported while that is true (for example, 0.19 at the time of writing is
quite old, but used by the most recent version of several popular crates).
- Versions which are not a significant maintenance burden will be supported
(for example, supporting versions older than winit 0.19 given that we
support 0.19).
- Explicitly removing support for a feature-indicated version will be
considered a breaking change.
- Changing the default feature to the new latest `winit` version is *not* a
breaking change.